Breaking and Bending Dashes (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Breaking and Bending Dashes
You can use polygon shapes and path shapes as dash shapes, which means you can have a dash shape that has multiple contours. The way that QuickDraw GX place dashes along a contour can cause dashes with multiple contours to appear quite a distance from the dashed contour. QuickDraw GX provides the break dash attribute (gxBreakDash) and the bend dash attribute (gxBendDash) to address this problem.
As an example, you can create a dash shape with two entirely separate contours: for example, two separate diamonds, as shown in Figure 3-67.
Figure 3-67 Dash shape with two contours

When you use this shape to dash any sort of curve, the larger diamond falls entirely off of the contour. Listing 3-15 creates a circle shape and dashes with the double diamond shape.
Listing 3-15 Creating a dash with multiple contours
void CreateDoubleDiamondDash(void)
{
   gxShape   aCircleShape, aDiamondShape;

   gxRectangle circleBounds = {ff(50), ff(50), ff(180), ff(180)};
   
   static long doubleDiamond[] = {2, /* number of contours */
                                  4, /* number of points */
                                  ff(0), ff(10), 
                                  ff(10), ff(0),
                                  ff(0), -ff(10), 
                                  -ff(10), ff(0),
                                  4, /* number of points */
                                  ff(40), ff(10), 
                                  ff(60), ff(0),
                                  ff(40), -ff(10), 
                                  ff(20), ff(0)};
      
   gxDashRecord theDashRecord;
   
   
   aCircleShape = NewArc(&circleBounds, ff(0), ff(360), false);
   GXSetShapeFill(aCircleShape, gxClosedFrameFill);

   aDiamondShape = GXNewPolygons((gxPolygons *) doubleDiamond);
      
   theDashRecord.attributes = gxAutoAdvanceDash;  
   theDashRecord.dash = aDiamondShape;
   theDashRecord.advance = ff(80); 
   theDashRecord.phase = GXFloatToFract(0.0); 
   theDashRecord.scale = ff(60); 

   GXSetShapeDash(aCircleShape, &theDashRecord);
   
   GXDisposeShape(aDiamondShape);
      
   GXSetShapePen(aCircleShape, ff(60));
   
   GXDrawShape(aCircleShape);
   
   GXDisposeShape(aCircleShape);
}
This sample function creates the shape depicted in Figure 3-68.
Figure 3-68 Circle dashed with double diamonds

The break dash attribute indicates that each contour of the dash shape should be separately rotated and placed on the contours of the dashed shape. If you set the break dash attribute in this example by replacing this line of code in the sample function:
theDashRecord.attributes = gxAutoAdvanceDash;  
with this line of code:
theDashRecord.attributes = gxAutoAdvanceDash | gxBreakDash;  
the resulting shape appears as shown in Figure 3-69.
Figure 3-69 Circle with dashes broken

In this case, QuickDraw GX rotates and centers the large diamond contours (separately from the small diamond contours) to fit the contour of the dashed shape.
If you change the pen width of the circle in this example to 0.0, you get a hairline curve, and the dashes are mapped down to their one-dimensional image. So, for example, setting the pen width with the call
GXSetShapePen(aCircleShape, ff(0));
causes the dashed circle to appear as in Figure 3-70.
Figure 3-70 Circle with hairline dashes

QuickDraw GX provides an extra feature for hairline dashes: you can bend them to fit curved contours exactly using the bend dash attribute (gxBendDash).
For example, if you change the dash attributes in this example using the assignment
theDashRecord.attributes = gxAutoAdvanceDash | gxBreakDash | 
                           gxBendDash;  
the dashed circle appears as shown in Figure 3-71.
Figure 3-71 Circle with bent hairline dashes

Note that you can specify the bend dash attribute only for hairline contours with broken dashes.
The sections "The Dash Structure" on page 3-103 and "Dash Attributes" on page 3-105 describe the dash record structure and dash attributes in more detail, and the section "Getting and Setting Dashes" beginning on page 3-134 describes the functions you can use to manipulate dashes.